includes/filerepo/backend/FSFileBackend.php

   1 <?php
   2 /**
   3  * @file
   4  * @ingroup FileBackend
   5  * @author Aaron Schulz
   6  */
   7
   8 /**
   9  * Class for a file system (FS) based file backend.
  10  *
  11  * All "containers" each map to a directory under the backend's base directory.
  12  * For backwards-compatibility, some container paths can be set to custom paths.
  13  * The wiki ID will not be used in any custom paths, so this should be avoided.
  14  *
  15  * Having directories with thousands of files will diminish performance.
  16  * Sharding can be accomplished by using FileRepo-style hash paths.
  17  *
  18  * Status messages should avoid mentioning the internal FS paths.
  19  * Likewise, error suppression should be used to avoid path disclosure.
  20  *
  21  * @ingroup FileBackend
  22  * @since 1.19
  23  */
  24 class FSFileBackend extends FileBackendStore {
  25         protected $basePath; // string; directory holding the container directories
  26         /** @var Array Map of container names to root paths */
  27         protected $containerPaths = array(); // for custom container paths
  28         protected $fileMode; // integer; file permission mode
  29
  30         protected $hadWarningErrors = array();
  31
  32         /**
  33          * @see FileBackendStore::__construct()
  34          * Additional $config params include:
  35          *    basePath       : File system directory that holds containers.
  36          *    containerPaths : Map of container names to custom file system directories.
  37          *                     This should only be used for backwards-compatibility.
  38          *    fileMode       : Octal UNIX file permissions to use on files stored.
  39          */
  40         public function __construct( array $config ) {
  41                 parent::__construct( $config );
  42
  43                 // Remove any possible trailing slash from directories
  44
  45                 if ( isset( $config['basePath'] ) ) {
  46                         $this->basePath = rtrim( $config['basePath'], '/' ); // remove trailing slash
  47                 } else {
  48                         $this->basePath = null; // none; containers must have explicit paths
  49                 }
  50
  51                 if( isset( $config['containerPaths'] ) ) {
  52                         $this->containerPaths = (array)$config['containerPaths'];
  53                         foreach ( $this->containerPaths as &$path ) {
  54                                 $path = rtrim( $path, '/' );  // remove trailing slash
  55                         }
  56                 }
  57
  58                 $this->fileMode = isset( $config['fileMode'] )
  59                         ? $config['fileMode']
  60                         : 0644;
  61         }
  62
  63         /**
  64          * @see FileBackendStore::resolveContainerPath()
  65          */
  66         protected function resolveContainerPath( $container, $relStoragePath ) {
  67                 // Check that container has a root directory
  68                 if ( isset( $this->containerPaths[$container] ) || isset( $this->basePath ) ) {
  69                         // Check for sane relative paths (assume the base paths are OK)
  70                         if ( $this->isLegalRelPath( $relStoragePath ) ) {
  71                                 return $relStoragePath;
  72                         }
  73                 }
  74                 return null;
  75         }
  76
  77         /**
  78          * Sanity check a relative file system path for validity
  79          *
  80          * @param $path string Normalized relative path
  81          * @return bool
  82          */
  83         protected function isLegalRelPath( $path ) {
  84                 // Check for file names longer than 255 chars
  85                 if ( preg_match( '![^/]{256}!', $path ) ) { // ext3/NTFS
  86                         return false;
  87                 }
  88                 if ( wfIsWindows() ) { // NTFS
  89                         return !preg_match( '![:*?"<>|]!', $path );
  90                 } else {
  91                         return true;
  92                 }
  93         }
  94
  95         /**
  96          * Given the short (unresolved) and full (resolved) name of
  97          * a container, return the file system path of the container.
  98          *
  99          * @param $shortCont string
 100          * @param $fullCont string
 101          * @return string|null
 102          */
 103         protected function containerFSRoot( $shortCont, $fullCont ) {
 104                 if ( isset( $this->containerPaths[$shortCont] ) ) {
 105                         return $this->containerPaths[$shortCont];
 106                 } elseif ( isset( $this->basePath ) ) {
 107                         return "{$this->basePath}/{$fullCont}";
 108                 }
 109                 return null; // no container base path defined
 110         }
 111
 112         /**
 113          * Get the absolute file system path for a storage path
 114          *
 115          * @param $storagePath string Storage path
 116          * @return string|null
 117          */
 118         protected function resolveToFSPath( $storagePath ) {
 119                 list( $fullCont, $relPath ) = $this->resolveStoragePathReal( $storagePath );
 120                 if ( $relPath === null ) {
 121                         return null; // invalid
 122                 }
 123                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $storagePath );
 124                 $fsPath = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 125                 if ( $relPath != '' ) {
 126                         $fsPath .= "/{$relPath}";
 127                 }
 128                 return $fsPath;
 129         }
 130
 131         /**
 132          * @see FileBackendStore::isPathUsableInternal()
 133          */
 134         public function isPathUsableInternal( $storagePath ) {
 135                 $fsPath = $this->resolveToFSPath( $storagePath );
 136                 if ( $fsPath === null ) {
 137                         return false; // invalid
 138                 }
 139                 $parentDir = dirname( $fsPath );
 140
 141                 wfSuppressWarnings();
 142                 if ( file_exists( $fsPath ) ) {
 143                         $ok = is_file( $fsPath ) && is_writable( $fsPath );
 144                 } else {
 145                         $ok = is_dir( $parentDir ) && is_writable( $parentDir );
 146                 }
 147                 wfRestoreWarnings();
 148
 149                 return $ok;
 150         }
 151
 152         /**
 153          * @see FileBackendStore::doStoreInternal()
 154          */
 155         protected function doStoreInternal( array $params ) {
 156                 $status = Status::newGood();
 157
 158                 $dest = $this->resolveToFSPath( $params['dst'] );
 159                 if ( $dest === null ) {
 160                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 161                         return $status;
 162                 }
 163
 164                 if ( file_exists( $dest ) ) {
 165                         if ( !empty( $params['overwrite'] ) ) {
 166                                 wfSuppressWarnings();
 167                                 $ok = unlink( $dest );
 168                                 wfRestoreWarnings();
 169                                 if ( !$ok ) {
 170                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 171                                         return $status;
 172                                 }
 173                         } else {
 174                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 175                                 return $status;
 176                         }
 177                 }
 178
 179                 wfSuppressWarnings();
 180                 $ok = copy( $params['src'], $dest );
 181                 wfRestoreWarnings();
 182                 if ( !$ok ) {
 183                         $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] );
 184                         return $status;
 185                 }
 186
 187                 $this->chmod( $dest );
 188
 189                 return $status;
 190         }
 191
 192         /**
 193          * @see FileBackendStore::doCopyInternal()
 194          */
 195         protected function doCopyInternal( array $params ) {
 196                 $status = Status::newGood();
 197
 198                 $source = $this->resolveToFSPath( $params['src'] );
 199                 if ( $source === null ) {
 200                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 201                         return $status;
 202                 }
 203
 204                 $dest = $this->resolveToFSPath( $params['dst'] );
 205                 if ( $dest === null ) {
 206                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 207                         return $status;
 208                 }
 209
 210                 if ( file_exists( $dest ) ) {
 211                         if ( !empty( $params['overwrite'] ) ) {
 212                                 wfSuppressWarnings();
 213                                 $ok = unlink( $dest );
 214                                 wfRestoreWarnings();
 215                                 if ( !$ok ) {
 216                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 217                                         return $status;
 218                                 }
 219                         } else {
 220                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 221                                 return $status;
 222                         }
 223                 }
 224
 225                 wfSuppressWarnings();
 226                 $ok = copy( $source, $dest );
 227                 wfRestoreWarnings();
 228                 if ( !$ok ) {
 229                         $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] );
 230                         return $status;
 231                 }
 232
 233                 $this->chmod( $dest );
 234
 235                 return $status;
 236         }
 237
 238         /**
 239          * @see FileBackendStore::doMoveInternal()
 240          */
 241         protected function doMoveInternal( array $params ) {
 242                 $status = Status::newGood();
 243
 244                 $source = $this->resolveToFSPath( $params['src'] );
 245                 if ( $source === null ) {
 246                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 247                         return $status;
 248                 }
 249
 250                 $dest = $this->resolveToFSPath( $params['dst'] );
 251                 if ( $dest === null ) {
 252                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 253                         return $status;
 254                 }
 255
 256                 if ( file_exists( $dest ) ) {
 257                         if ( !empty( $params['overwrite'] ) ) {
 258                                 // Windows does not support moving over existing files
 259                                 if ( wfIsWindows() ) {
 260                                         wfSuppressWarnings();
 261                                         $ok = unlink( $dest );
 262                                         wfRestoreWarnings();
 263                                         if ( !$ok ) {
 264                                                 $status->fatal( 'backend-fail-delete', $params['dst'] );
 265                                                 return $status;
 266                                         }
 267                                 }
 268                         } else {
 269                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 270                                 return $status;
 271                         }
 272                 }
 273
 274                 wfSuppressWarnings();
 275                 $ok = rename( $source, $dest );
 276                 clearstatcache(); // file no longer at source
 277                 wfRestoreWarnings();
 278                 if ( !$ok ) {
 279                         $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] );
 280                         return $status;
 281                 }
 282
 283                 return $status;
 284         }
 285
 286         /**
 287          * @see FileBackendStore::doDeleteInternal()
 288          */
 289         protected function doDeleteInternal( array $params ) {
 290                 $status = Status::newGood();
 291
 292                 $source = $this->resolveToFSPath( $params['src'] );
 293                 if ( $source === null ) {
 294                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 295                         return $status;
 296                 }
 297
 298                 if ( !is_file( $source ) ) {
 299                         if ( empty( $params['ignoreMissingSource'] ) ) {
 300                                 $status->fatal( 'backend-fail-delete', $params['src'] );
 301                         }
 302                         return $status; // do nothing; either OK or bad status
 303                 }
 304
 305                 wfSuppressWarnings();
 306                 $ok = unlink( $source );
 307                 wfRestoreWarnings();
 308                 if ( !$ok ) {
 309                         $status->fatal( 'backend-fail-delete', $params['src'] );
 310                         return $status;
 311                 }
 312
 313                 return $status;
 314         }
 315
 316         /**
 317          * @see FileBackendStore::doCreateInternal()
 318          */
 319         protected function doCreateInternal( array $params ) {
 320                 $status = Status::newGood();
 321
 322                 $dest = $this->resolveToFSPath( $params['dst'] );
 323                 if ( $dest === null ) {
 324                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 325                         return $status;
 326                 }
 327
 328                 if ( file_exists( $dest ) ) {
 329                         if ( !empty( $params['overwrite'] ) ) {
 330                                 wfSuppressWarnings();
 331                                 $ok = unlink( $dest );
 332                                 wfRestoreWarnings();
 333                                 if ( !$ok ) {
 334                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 335                                         return $status;
 336                                 }
 337                         } else {
 338                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 339                                 return $status;
 340                         }
 341                 }
 342
 343                 wfSuppressWarnings();
 344                 $bytes = file_put_contents( $dest, $params['content'] );
 345                 wfRestoreWarnings();
 346                 if ( $bytes === false ) {
 347                         $status->fatal( 'backend-fail-create', $params['dst'] );
 348                         return $status;
 349                 }
 350
 351                 $this->chmod( $dest );
 352
 353                 return $status;
 354         }
 355
 356         /**
 357          * @see FileBackendStore::doPrepareInternal()
 358          */
 359         protected function doPrepareInternal( $fullCont, $dirRel, array $params ) {
 360                 $status = Status::newGood();
 361                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 362                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 363                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 364                 if ( !wfMkdirParents( $dir ) ) { // make directory and its parents
 365                         $status->fatal( 'directorycreateerror', $params['dir'] );
 366                 } elseif ( !is_writable( $dir ) ) {
 367                         $status->fatal( 'directoryreadonlyerror', $params['dir'] );
 368                 } elseif ( !is_readable( $dir ) ) {
 369                         $status->fatal( 'directorynotreadableerror', $params['dir'] );
 370                 }
 371                 return $status;
 372         }
 373
 374         /**
 375          * @see FileBackendStore::doSecureInternal()
 376          */
 377         protected function doSecureInternal( $fullCont, $dirRel, array $params ) {
 378                 $status = Status::newGood();
 379                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 380                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 381                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 382                 // Seed new directories with a blank index.html, to prevent crawling...
 383                 if ( !empty( $params['noListing'] ) && !file_exists( "{$dir}/index.html" ) ) {
 384                         wfSuppressWarnings();
 385                         $bytes = file_put_contents( "{$dir}/index.html", '' );
 386                         wfRestoreWarnings();
 387                         if ( !$bytes ) {
 388                                 $status->fatal( 'backend-fail-create', $params['dir'] . '/index.html' );
 389                                 return $status;
 390                         }
 391                 }
 392                 // Add a .htaccess file to the root of the container...
 393                 if ( !empty( $params['noAccess'] ) ) {
 394                         if ( !file_exists( "{$contRoot}/.htaccess" ) ) {
 395                                 wfSuppressWarnings();
 396                                 $bytes = file_put_contents( "{$contRoot}/.htaccess", "Deny from all\n" );
 397                                 wfRestoreWarnings();
 398                                 if ( !$bytes ) {
 399                                         $storeDir = "mwstore://{$this->name}/{$shortCont}";
 400                                         $status->fatal( 'backend-fail-create', "{$storeDir}/.htaccess" );
 401                                         return $status;
 402                                 }
 403                         }
 404                 }
 405                 return $status;
 406         }
 407
 408         /**
 409          * @see FileBackendStore::doCleanInternal()
 410          */
 411         protected function doCleanInternal( $fullCont, $dirRel, array $params ) {
 412                 $status = Status::newGood();
 413                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 414                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 415                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 416                 wfSuppressWarnings();
 417                 if ( is_dir( $dir ) ) {
 418                         rmdir( $dir ); // remove directory if empty
 419                 }
 420                 wfRestoreWarnings();
 421                 return $status;
 422         }
 423
 424         /**
 425          * @see FileBackendStore::doFileExists()
 426          */
 427         protected function doGetFileStat( array $params ) {
 428                 $source = $this->resolveToFSPath( $params['src'] );
 429                 if ( $source === null ) {
 430                         return false; // invalid storage path
 431                 }
 432
 433                 $this->trapWarnings();
 434                 $stat = is_file( $source ) ? stat( $source ) : false; // regular files only
 435                 $hadError = $this->untrapWarnings();
 436
 437                 if ( $stat ) {
 438                         return array(
 439                                 'mtime' => wfTimestamp( TS_MW, $stat['mtime'] ),
 440                                 'size'  => $stat['size']
 441                         );
 442                 } elseif ( !$hadError ) {
 443                         return false; // file does not exist
 444                 } else {
 445                         return null; // failure
 446                 }
 447         }
 448
 449         /**
 450          * @see FileBackendStore::doClearCache()
 451          */
 452         protected function doClearCache( array $paths = null ) {
 453                 clearstatcache(); // clear the PHP file stat cache
 454         }
 455
 456         /**
 457          * @see FileBackendStore::getFileListInternal()
 458          */
 459         public function getFileListInternal( $fullCont, $dirRel, array $params ) {
 460                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 461                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 462                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 463                 wfSuppressWarnings();
 464                 $exists = is_dir( $dir );
 465                 wfRestoreWarnings();
 466                 if ( !$exists ) {
 467                         wfDebug( __METHOD__ . "() given directory does not exist: '$dir'\n" );
 468                         return array(); // nothing under this dir
 469                 }
 470                 wfSuppressWarnings();
 471                 $readable = is_readable( $dir );
 472                 wfRestoreWarnings();
 473                 if ( !$readable ) {
 474                         wfDebug( __METHOD__ . "() given directory is unreadable: '$dir'\n" );
 475                         return null; // bad permissions?
 476                 }
 477                 return new FSFileBackendFileList( $dir );
 478         }
 479
 480         /**
 481          * @see FileBackendStore::getLocalReference()
 482          */
 483         public function getLocalReference( array $params ) {
 484                 $source = $this->resolveToFSPath( $params['src'] );
 485                 if ( $source === null ) {
 486                         return null;
 487                 }
 488                 return new FSFile( $source );
 489         }
 490
 491         /**
 492          * @see FileBackendStore::getLocalCopy()
 493          */
 494         public function getLocalCopy( array $params ) {
 495                 $source = $this->resolveToFSPath( $params['src'] );
 496                 if ( $source === null ) {
 497                         return null;
 498                 }
 499
 500                 // Create a new temporary file with the same extension...
 501                 $ext = FileBackend::extensionFromPath( $params['src'] );
 502                 $tmpFile = TempFSFile::factory( wfBaseName( $source ) . '_', $ext );
 503                 if ( !$tmpFile ) {
 504                         return null;
 505                 }
 506                 $tmpPath = $tmpFile->getPath();
 507
 508                 // Copy the source file over the temp file
 509                 wfSuppressWarnings();
 510                 $ok = copy( $source, $tmpPath );
 511                 wfRestoreWarnings();
 512                 if ( !$ok ) {
 513                         return null;
 514                 }
 515
 516                 $this->chmod( $tmpPath );
 517
 518                 return $tmpFile;
 519         }
 520
 521         /**
 522          * Chmod a file, suppressing the warnings
 523          *
 524          * @param $path string Absolute file system path
 525          * @return bool Success
 526          */
 527         protected function chmod( $path ) {
 528                 wfSuppressWarnings();
 529                 $ok = chmod( $path, $this->fileMode );
 530                 wfRestoreWarnings();
 531
 532                 return $ok;
 533         }
 534
 535         /**
 536          * Suppress E_WARNING errors and track whether any happen
 537          *
 538          * @return void
 539          */
 540         protected function trapWarnings() {
 541                 $this->hadWarningErrors[] = false; // push to stack
 542                 set_error_handler( array( $this, 'handleWarning' ), E_WARNING );
 543         }
 544
 545         /**
 546          * Unsuppress E_WARNING errors and return true if any happened
 547          *
 548          * @return bool
 549          */
 550         protected function untrapWarnings() {
 551                 restore_error_handler(); // restore previous handler
 552                 return array_pop( $this->hadWarningErrors ); // pop from stack
 553         }
 554
 555         private function handleWarning() {
 556                 $this->hadWarningErrors[count( $this->hadWarningErrors ) - 1] = true;
 557                 return true; // suppress from PHP handler
 558         }
 559 }
 560
 561 /**
 562  * Wrapper around RecursiveDirectoryIterator that catches
 563  * exception or does any custom behavoir that we may want.
 564  * Do not use this class from places outside FSFileBackend.
 565  *
 566  * @ingroup FileBackend
 567  */
 568 class FSFileBackendFileList implements Iterator {
 569         /** @var RecursiveIteratorIterator */
 570         protected $iter;
 571         protected $suffixStart; // integer
 572         protected $pos = 0; // integer
 573
 574         /**
 575          * @param $dir string file system directory
 576          */
 577         public function __construct( $dir ) {
 578                 $dir = realpath( $dir ); // normalize
 579                 $this->suffixStart = strlen( $dir ) + 1; // size of "path/to/dir/"
 580                 try {
 581                         # Get an iterator that will return leaf nodes (non-directories)
 582                         if ( MWInit::classExists( 'FilesystemIterator' ) ) { // PHP >= 5.3
 583                                 # RecursiveDirectoryIterator extends FilesystemIterator.
 584                                 # FilesystemIterator::SKIP_DOTS default is inconsistent in PHP 5.3.x.
 585                                 $flags = FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS;
 586                                 $this->iter = new RecursiveIteratorIterator(
 587                                         new RecursiveDirectoryIterator( $dir, $flags ) );
 588                         } else { // PHP < 5.3
 589                                 # RecursiveDirectoryIterator extends DirectoryIterator
 590                                 $this->iter = new RecursiveIteratorIterator(
 591                                         new RecursiveDirectoryIterator( $dir ) );
 592                         }
 593                 } catch ( UnexpectedValueException $e ) {
 594                         $this->iter = null; // bad permissions? deleted?
 595                 }
 596         }
 597
 598         public function current() {
 599                 // Return only the relative path and normalize slashes to FileBackend-style
 600                 // Make sure to use the realpath since the suffix is based upon that
 601                 return str_replace( '\\', '/',
 602                         substr( realpath( $this->iter->current() ), $this->suffixStart ) );
 603         }
 604
 605         public function key() {
 606                 return $this->pos;
 607         }
 608
 609         public function next() {
 610                 try {
 611                         $this->iter->next();
 612                 } catch ( UnexpectedValueException $e ) {
 613                         $this->iter = null;
 614                 }
 615                 ++$this->pos;
 616         }
 617
 618         public function rewind() {
 619                 $this->pos = 0;
 620                 try {
 621                         $this->iter->rewind();
 622                 } catch ( UnexpectedValueException $e ) {
 623                         $this->iter = null;
 624                 }
 625         }
 626
 627         public function valid() {
 628                 return $this->iter && $this->iter->valid();
 629         }
 630 }